docs/Customized Version.md

   1 # Create a Customized Version
   2
   3 The flight controllers have some limitations in space and computing capacity. The developers must decide what features enable and what others disable to create a firmware file that can be used for the major part or users.
   4
   5 For example, the official firmware published to users include support for a lot of brands of transmitters and receivers, but habitually you will use only one. This is necessary for a public version, but the protocols not used are spending space that can be used for other features.
   6
   7 This document gives a little guide of how-to start creating your own version, activating and deactivating features, especially if your flight controller is an older one with not too much space.
   8
   9 Keep in mind that when you create your own firmware you're using a piece of software created by you and can have some bugs that are not present in official version. **You use it at your own risk**.
  10
  11 ## Build the firmware
  12
  13 This document is aimed to people who has some knowledge about programming skills and can build its own firmware. You can find information about this process in the [`development`](development/) documentation page.
  14
  15 Once you are able to compile your own firmware, you can continue to the next section of this document.
  16
  17 When you compile the firmware, the `make` process ends with an info summary of the firmware created, something like this:
  18 ```
  19    text    data     bss     dec     hex filename
  20  126312    1444   18260  146016   23a60 ./obj/main/cleanflight_NAZE.elf
  21 ```
  22
  23 The 'text + data' gives you the flash size, and the 'data + bss' is the (static) ram usage. It's recommended to keep the customized version under the values of the unmodified version.
  24
  25 ## Commons features for all Flight Controllers
  26
  27 The first file where the developers specify the features that are activated or not for a flight controller, is the `target/common_pre.h`.
  28
  29 This file specifies the features enabled/disabled depending on the memory flash size of the flight controller, or other conditions.
  30
  31 The first interesting part is where it specifies the features activated for all flight controllers. In the actual version, for example:
  32 ```
  33 #define USE_CLI
  34 #define USE_PPM
  35 #define USE_PWM
  36 #define SERIAL_RX
  37 #define USE_SERIALRX_CRSF       // Team Black Sheep Crossfire protocol
  38 #define USE_SERIALRX_IBUS       // FlySky and Turnigy receivers
  39 #define USE_SERIALRX_SBUS       // Frsky and Futaba receivers
  40 #define USE_SERIALRX_SPEKTRUM   // SRXL, DSM2 and DSMX protocol
  41 #define USE_SERIALRX_SUMD       // Graupner Hott protocol
  42 #define USE_SERIALRX_SUMH       // Graupner legacy protocol
  43 #define USE_SERIALRX_XBUS       // JR
  44 ```
  45
  46 The next part are features enabled if your memory flash size is bigger than 64 megabits.
  47 ```
  48 #if (FLASH_SIZE > 64)
  49 #define BLACKBOX
  50 #define LED_STRIP
  51 #define TELEMETRY
  52 #define TELEMETRY_FRSKY
  53 #define TELEMETRY_HOTT
  54 #define TELEMETRY_LTM
  55 #define TELEMETRY_SMARTPORT
  56 #define USE_RESOURCE_MGMT
  57 #define USE_SERVOS
  58 #endif
  59 ```
  60
  61 And bigger than 128 megabits:
  62 ```
  63 #if (FLASH_SIZE > 128)
  64 #define GPS
  65 #define CMS
  66 #define TELEMETRY_CRSF
  67 #define TELEMETRY_IBUS
  68 #define TELEMETRY_JETIEXBUS
  69 #define TELEMETRY_MAVLINK
  70 #define TELEMETRY_SRXL
  71 #define USE_DASHBOARD
  72 #define USE_MSP_DISPLAYPORT
  73 #define USE_RX_MSP
  74 #define USE_SERIALRX_JETIEXBUS
  75 #define USE_SENSOR_NAMES
  76 #define VTX_COMMON
  77 #define VTX_CONTROL
  78 #define VTX_SMARTAUDIO
  79 #define VTX_TRAMP
  80 #endif
  81 ```
  82
  83 Another interesting thing of this file, are others features deactivated by the computing capacity of the flight controller, or the model of the processor. For example:
  84 ```
  85 #if (__FPU_PRESENT == 1) && (__FPU_USED == 1)
  86 #define DEFAULT_AUX_CHANNEL_COUNT       MAX_AUX_CHANNEL_COUNT
  87 #else
  88 #define DEFAULT_AUX_CHANNEL_COUNT       6
  89 #endif
  90 ```
  91 If the flight controller hasn't a FPU (F1 processors for example) you can use only 6 auxiliary channels of the receiver.
  92
  93 After looking carefully to this file, you must know what features you want to disable or enable in your customized build.
  94
  95 *NOTE: It is better to not change this file, but it's useful to see what features you can activate or deactivate in your custom build.*
  96
  97 ## Specific features for each Flight Controller
  98
  99 Each flight controller has it's own file to specify what features are enabled or disable only for it. Sometimes they have been disabled by space limitations, but other times it's for limited computing capacity or a bug, so enable it at your own risk.
 100
 101 This file is located in `target/[FLIGHT_CONTROLLER_NAME]/target.h` and it's loaded **after** the `target/common_pre.h`. So any changes in this file will overwrite the default settings, so this file is the place where you must touch to create your custom firmware.
 102
 103 The first thing to do is to *#undef* all the features that we want to disable from the *common_pre.h*.
 104
 105 For example, in a NAZE32, if we're using Serial RX, with a FlySky receiver (that uses de iBus protocol) and we don't have a led strip we will add all this *#undef* to the file.
 106
 107 ```
 108 #undef USE_PPM
 109 #undef USE_PWM
 110 #undef USE_SERIALRX_CRSF       // Team Black Sheep Crossfire protocol
 111 #undef USE_SERIALRX_SBUS       // Frsky and Futaba receivers
 112 #undef USE_SERIALRX_SPEKTRUM   // SRXL, DSM2 and DSMX protocol
 113 #undef USE_SERIALRX_SUMD       // Graupner Hott protocol
 114 #undef USE_SERIALRX_SUMH       // Graupner legacy protocol
 115 #undef USE_SERIALRX_XBUS       // JR
 116
 117 #undef LED_STRIP
 118 #undef TELEMETRY_FRSKY
 119 #undef TELEMETRY_HOTT
 120 #undef TELEMETRY_LTM
 121 #undef TELEMETRY_SMARTPORT
 122 #undef USE_SERVOS
 123 ```
 124
 125 With this change, we have won space to add some missing features. With this space, we will add GPS and telemetry by iBus too, adding some *#define* that are only activated by default for flight controllers with more than 128 megabits:
 126 ```
 127 #define GPS
 128 #define TELEMETRY_IBUS
 129 ```
 130
 131 Be careful, some features are dependent, for example, the `TELEMETRY_IBUS` needs the `TELEMETRY` enabled.
 132
 133 To customize more if needed, this file defines all the hardware supported by different versions of the flight controller, for example, in the `NAZE` file:
 134 ```
 135 #define GYRO
 136 #define USE_GYRO_MPU3050
 137 #define USE_GYRO_MPU6050
 138 #define USE_GYRO_MPU6500
 139 #define USE_GYRO_SPI_MPU6500
 140
 141 #define ACC
 142 #define USE_ACC_ADXL345
 143 #define USE_ACC_BMA280
 144 #define USE_ACC_MMA8452
 145 #define USE_ACC_MPU6050
 146 #define USE_ACC_MPU6500
 147 #define USE_ACC_SPI_MPU6500
 148
 149 #define BARO
 150 #define USE_BARO_MS5611 // needed for Flip32 board
 151 #define USE_BARO_BMP280
 152 ```
 153 Here you have different gyroscopes, accelerometers and barometers defined, to support all the variants of the flight controller. You can comment all the models that you're sure that your flight controller is not using and you will get some free space.
 154
 155 You can find too some features disabled for this flight controller, in this case, for example:
 156 ```
 157 /*
 158 #define MAG
 159 #define USE_MAG_HMC5883
 160 #define MAG_HMC5883_ALIGN       CW180_DEG
 161 */
 162 ```
 163
 164 The magnetometer is commented.  If you uncomment it, then it will be activated and you can use it in the NAZE flight controller.
 165
 166 After modifying this file, you only need to build your firmware again and you will have your own customized version with all and only the features that you need.
 167
 168 ## Final considerations
 169
 170 As has been said several times in this document, when you activate a feature disabled by the developers, you can overcharge the processor, or include a bug in your firmware version. **So be careful and do it at your own risk**.